{
 "metadata": {
  "signature": "sha256:d9fc529106eb89f14df2f8769a4c48b1f882491b9a039f8464f10e0f5a7a7fa2"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Scripting Mayavi 2: main modules\n",
      "======================================================================\n",
      "\n",
      "Introduction\n",
      "------------\n",
      "\n",
      "Here's the real stuff ;-)\n",
      "\n",
      "You'll be learned here how you can use the various modules in !MayaVi2.\n",
      "\n",
      "Note: Some modules can't be added for any type of data set. Some work\n",
      "only for !StructuredGrid or !StructuredPoints for example (see\n",
      "<http://www.vtk.org/pdf/file-formats.pdf> for more information about VTK\n",
      "data type). It will be specified each time is needed.\n",
      "\n",
      "Note2: In the !MayaVi2 tree view, the \"Main Modules\" (called \"Modules\")\n",
      "have been separated from the \"Basic Modules\" loading the !ModuleManager.\n",
      "Of coutse, you can load all your modules and filters without using the\n",
      "!ModuleManager.\n",
      "\n",
      "ImagePlaneWidget/ScalarCutPlane/SliceUnstructuredGrid module\n",
      "------------------------------------------------------------\n",
      "\n",
      "The simpliest (and easiest, but not the most impressive ;-) ) way to\n",
      "display 3D data is doubtless to slice it on some planes, normal to Ox,\n",
      "Oy or Oz axis, or oblique.\n",
      "\n",
      "One of the modules you can use to do this is called !ScalarCutPlane. It\n",
      "works for any data.\n",
      "\n",
      "Note: As the !ImagePlaneWidget module also display scalars data on a\n",
      "plane (but it does not \"cut\" data), please see\n",
      "[:Cookbook/MayaVi/Examples: Example with a 3D array as numerical source\n",
      "(numeric\\_source.py)] or [:Cookbook/MayaVi/Examples: Example using\n",
      "ImagePlaneWidget Module (test.py)] to get more information on how you\n",
      "can use this module.\n",
      "\n",
      "You have to set several parameters:\n",
      "\n",
      "`*\u00a0plane\u00a0normal;`\\\n",
      "`*\u00a0its\u00a0origin;`\\\n",
      "`*\u00a0widget\u00a0enabled\u00a0or\u00a0not:\u00a0if\u00a0enabled,\u00a0you\u00a0can\u00a0play\u00a0with\u00a0the\u00a0mouse\u00a0to\u00a0modify\u00a0normal\u00a0orientation,\u00a0position,\u00a0etc.;`\\\n",
      "`*\u00a0some\u00a0colors\u00a0properties.`\n",
      "\n",
      "Thus, you have to type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.scalar_cut_plane import ScalarCutPlane"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "and"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "scp = ScalarCutPlane() # set scp as ScalarCutPlane() module\n",
      "script.add_module(scp) # add module to the scene\n",
      "scp.implicit_plane.normal = (1, 0, 0) # set normal to Ox axis\n",
      "# set origin to (i=10, j=25, k=25) i.e. integers for a structured grid\n",
      "scp.implicit_plane.origin = (10, 25, 25)\n",
      "# set origin to (x=1.0, y=2.5, z=2.5) i.e. reals for unstructured grids\n",
      "# scp.implicit_plane.origin = (1.0, 2.5, 2.5)\n",
      "scp.implicit_plane.widget.enabled = False\n",
      "scp.actor.property.diffuse = 0.0 # set some color properties\n",
      "scp.actor.property.ambient = 1.0 # \n",
      "scp.actor.property.opacity = 1.0 #\n",
      "scp.module_manager.scalar_lut_manager.data_range = [0, 1]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_scp.png)\n",
      "\n",
      "Note that if you enable widget, you will be able to translate (move the\n",
      "mouse to the red frame), change the normal (move the mouse to the grey\n",
      "arrow) of the cutplanes in \"real-time\" :\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_scp_widg_en.png)\n",
      "\n",
      "You can also display the cutplanes as \"warped surfaces\", just adding a\n",
      "few lines, setting the scale factor and the normals to be computed\n",
      "(smoother surface) or not:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "scp.enable_warp_scalar = True\n",
      "scp.compute_normals = True\n",
      "scp.warp_scalar.filter.scale_factor = 20"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_scp_warp.png)\n",
      "\n",
      "Of course, you can add as many cutplanes as you want, oblique or not.\n",
      "\n",
      "Let's see now a little more complex example : we want opacity to be set\n",
      "to 0.2 for each cutplane, and contours (\\#10) for the same cutplanes\n",
      "added. Lines above have been changed as below:\n",
      "\n",
      "Note: I agree, this is not the best way to write such a code. You can\n",
      "obviously write a method to do the same suff. But this is not the\n",
      "purpose here."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "### cutplane #1, normal to Ox, opacity = 0.2, representation = surface\n",
      "scp = ScalarCutPlane()\n",
      "script.add_module(scp)\n",
      "scp.implicit_plane.normal = (1, 0, 0)\n",
      "scp.implicit_plane.origin = (25, 25, 25)\n",
      "scp.implicit_plane.widget.enabled = False\n",
      "scp.actor.property.diffuse = 0.0\n",
      "scp.actor.property.ambient = 1.0\n",
      "scp.actor.property.opacity = 0.2\n",
      "scp.module_manager.scalar_lut_manager.data_range = [0, 1]\n",
      "\n",
      "### cutplane #2, normal to Oy, opacity = 0.2, representation = surface\n",
      "scp = ScalarCutPlane()\n",
      "script.add_module(scp)\n",
      "scp.implicit_plane.normal = (0, 1, 0)\n",
      "scp.implicit_plane.origin = (25, 25, 25)\n",
      "scp.implicit_plane.widget.enabled = False\n",
      "scp.actor.property.diffuse = 0.0\n",
      "scp.actor.property.ambient = 1.0\n",
      "scp.actor.property.opacity = 0.2\n",
      "scp.module_manager.scalar_lut_manager.data_range = [0, 1]\n",
      "\n",
      "### cutplane #3, normal to Oz, opacity = 0.2, representation = surface\n",
      "scp = ScalarCutPlane()\n",
      "script.add_module(scp)\n",
      "scp.implicit_plane.normal = (0, 0, 1)\n",
      "scp.implicit_plane.origin = (25, 25, 25)\n",
      "scp.implicit_plane.widget.enabled = False\n",
      "scp.actor.property.diffuse = 0.0\n",
      "scp.actor.property.ambient = 1.0\n",
      "scp.actor.property.opacity = 0.2\n",
      "scp.module_manager.scalar_lut_manager.data_range = [0, 1]\n",
      "\n",
      "### cutplane #4, normal to Ox, representation = contour\n",
      "scp = ScalarCutPlane()\n",
      "script.add_module(scp)\n",
      "scp.implicit_plane.normal = (1, 0, 0)\n",
      "scp.implicit_plane.origin = (25, 25, 25)\n",
      "scp.implicit_plane.widget.enabled = False\n",
      "scp.actor.property.diffuse = 0.0\n",
      "scp.actor.property.ambient = 1.0\n",
      "scp.enable_contours = True\n",
      "scp.contour.number_of_contours = 10\n",
      "scp.contour.minimum_contour, scp.contour.maximum_contour = [0, 1]\n",
      "scp.module_manager.scalar_lut_manager.data_range = [0, 1]\n",
      "\n",
      "### cutplane #5, normal to Oy, representation = contour\n",
      "scp = ScalarCutPlane()\n",
      "script.add_module(scp)\n",
      "scp.implicit_plane.normal = (0, 1, 0)\n",
      "scp.implicit_plane.origin = (25, 25, 25)\n",
      "scp.implicit_plane.widget.enabled = False\n",
      "scp.actor.property.diffuse = 0.0\n",
      "scp.actor.property.ambient = 1.0\n",
      "scp.enable_contours = True\n",
      "scp.contour.number_of_contours = 10\n",
      "scp.contour.minimum_contour, scp.contour.maximum_contour = [0, 1]\n",
      "scp.module_manager.scalar_lut_manager.data_range = [0, 1]\n",
      "\n",
      "### cutplane #6, normal to Oz, representation = contour\n",
      "scp = ScalarCutPlane()\n",
      "script.add_module(scp)\n",
      "scp.implicit_plane.normal = (0, 0, 1)\n",
      "scp.implicit_plane.origin = (25, 25, 25)\n",
      "scp.implicit_plane.widget.enabled = False\n",
      "scp.actor.property.diffuse = 0.0\n",
      "scp.actor.property.ambient = 1.0\n",
      "scp.enable_contours = True\n",
      "scp.contour.number_of_contours = 10\n",
      "scp.contour.minimum_contour, scp.contour.maximum_contour = [0, 1]\n",
      "scp.module_manager.scalar_lut_manager.data_range = [0, 1]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "which looks like this:\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_scp2.png)\n",
      "\n",
      "Another module that slices grid is called !SliceUnstructuredGrid. As it\n",
      "is called, it should work only for unstructured grids. But, because it\n",
      "has been tested on a structured grid, even !MayaVi2 complains about it\n",
      "with a warning message, it \"works\" even for structured grid (happily for\n",
      "our example ;-) )\n",
      "\n",
      "In fact, its interest is not really slicing grid, but even more showing\n",
      "the structure of your mesh, i.e. your mesh cells. Thus you can see if\n",
      "there is not any problem (holes, etc.)."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.slice_unstructured_grid import SliceUnstructuredGrid"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "and"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "sug = SliceUnstructuredGrid()\n",
      "script.add_module(sug)\n",
      "# unstructured grid so origin coordinates are reals\n",
      "sug.implicit_plane.origin = (25., 25., 25.)\n",
      "sug.implicit_plane.normal = (1, 1, 1)\n",
      "sug.implicit_plane.widget.enabled = False\n",
      "sug.extract_geometry.extract_boundary_cells = False\n",
      "sug.extract_geometry.extract_inside = True\n",
      "sug.extract_geometry.extract_only_boundary_cells = False\n",
      "sug.geom_filter.cell_clipping = False\n",
      "sug.geom_filter.extent_clipping = False\n",
      "sug.geom_filter.merging = True\n",
      "sug.geom_filter.point_clipping = False\n",
      "sug.actor.property.representation = 'wireframe'\n",
      "sug.actor.property.diffuse = 0.0\n",
      "sug.actor.property.ambient = 1.0 \n",
      "sug.actor.property.opacity = 1.0\n",
      "sug.module_manager.scalar_lut_manager.data_range = [0, 1]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The scene should look like this:\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_sug.png)\n",
      "\n",
      "GridPlane/StructuredGridOutline module\n",
      "--------------------------------------\n",
      "\n",
      "Using !GridPlane module cuts also your grid, but quite differently from\n",
      "!ScalarCutPlane module. You can't get normal plane only along Ox, Oy and\n",
      "Oz axis, and it works only for structured grids. But unlike\n",
      "!ScalarCutPlane module, which always cuts your mesh in a plane,\n",
      "!GridPlane cuts through your mesh: if it's a conformal mesh, the cut\n",
      "won't be a plane, but something following the curvature of your mesh.\n",
      "\n",
      "The !StructuredGridOutline module does the same as Outline module, but\n",
      "for conformal mesh.\n",
      "\n",
      "To illustrate how can we use these modules, let's consider a example\n",
      "provided in the VTKData directory, combxyz.bin & combq.bin files (Plot3D\n",
      "format) from the tarball vtkdata-5.0.3.tar.gz you can download\n",
      "[here](http://www.vtk.org/get-software.php#latest).\n",
      "\n",
      "So, type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.strucured_grid_outline import StructuredGridOutline\n",
      "from enthought.mayavi.modules.grid_plane import GridPlane\n",
      "\n",
      "# to load Plot3D files format\n",
      "from enthought.mayavi.sources.plot3d_reader import PLOT3DReader"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "and"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "src = PLOT3DReader()\n",
      "src.initialize('combxyz.bin', 'combq.bin')\n",
      "script.add_source(src)\n",
      "\n",
      "sgo = StructuredGridOutline()\n",
      "script.add_module(sgo)\n",
      "    \n",
      "gp = GridPlane()\n",
      "script.add_module(gp)\n",
      "gp.grid_plane.axis = 'x'\n",
      "gp.grid_plane.position = 2\n",
      "gp.actor.mapper.scalar_visibility = True\n",
      "gp.actor.property.representation = 'surface'\n",
      "gp.actor.property.diffuse = 0.0\n",
      "gp.actor.property.ambient = 1.0\n",
      "gp.actor.property.opacity = 1\n",
      "\n",
      "gp = GridPlane()\n",
      "script.add_module(gp)\n",
      "gp.grid_plane.axis = 'x'\n",
      "gp.grid_plane.position = 25\n",
      "gp.actor.mapper.scalar_visibility = True\n",
      "gp.actor.property.representation = 'surface'\n",
      "gp.actor.property.diffuse = 0.0\n",
      "gp.actor.property.ambient = 1.0\n",
      "gp.actor.property.opacity = 1\n",
      "\n",
      "gp = GridPlane()\n",
      "script.add_module(gp)\n",
      "gp.grid_plane.axis = 'x'\n",
      "gp.grid_plane.position = 55\n",
      "gp.actor.mapper.scalar_visibility = True\n",
      "gp.actor.property.representation = 'surface'\n",
      "gp.actor.property.diffuse = 0.0\n",
      "gp.actor.property.ambient = 1.0\n",
      "gp.actor.property.opacity = 1"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The scene is rendered as this:\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_sgo_gp.png)\n",
      "\n",
      "Surface/IsoSurface module\n",
      "-------------------------\n",
      "\n",
      "Others modules are Surface and !IsoSurface. These modules work with any\n",
      "data.\n",
      "\n",
      "Surface module does the same as !IsoSurface but displays, automatically,\n",
      "several isosurfaces for a given number of values in a given range.\n",
      "\n",
      "In fact, you can get the same result with !IsoSurface module, but you\n",
      "will have to set each isovalue.\n",
      "\n",
      "When several isosurfaces are displayed, using Surface or !IsoSurface\n",
      "module, you should set opacity to a value below 1, in order to see all\n",
      "isosurfaces.\n",
      "\n",
      "Using Surface module is straightforward:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.surface import Surface"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "then"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "s = Surface()\n",
      "s.enable_contours = True # we want contours enabled\n",
      "s.contour.auto_contours = True # we want isovalues automatically well-defined\n",
      "s.contour.number_of_contours = 10 # self-explanatory ;-)\n",
      "s.actor.property.opacity = 0.2\n",
      "script.add_module(s)\n",
      "s.contour.minimum_contour = 0\n",
      "s.contour.maximum_contour = 1\n",
      "s.module_manager.scalar_lut_manager.data_range = [0, 1]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The scene should look like this:\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_surface.png)\n",
      "\n",
      "Using the !IsoSurface module is not more difficult. As an example, say\n",
      "that we want the same result as the Surface module displays."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.iso_surface import IsoSurface"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "and"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "isosurf = IsoSurface()\n",
      "script.add_module(isosurf)\n",
      "isosurf.contour.contours = [0.1111, 0.2222, 0.3333, 0.4444, 0.5555, 0.6666, 0.7777, 0.8888]\n",
      "isosurf.compute_normals = True\n",
      "isosurf.actor.property.opacity = 0.2\n",
      "isosurf.module_manager.scalar_lut_manager.data_range = [0, 1]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This yelds the same scene as previous, of course, but now, you can\n",
      "control each isovalue separately.\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_isosurface.png)\n",
      "\n",
      "The funny part is that you can set the minimum/maximum contour for\n",
      "Surface or Contours for !IsoSurface in \"real-time\", moving the\n",
      "slide-bar. This is a very useful feature. And can render very nice\n",
      "\"dynamic\" scene ! :-)\n",
      "\n",
      "Volume module\n",
      "-------------\n",
      "\n",
      "It is still quite experimental for me (you can set a lot of parameters),\n",
      "so this section will be very short ;-)\n",
      "\n",
      "Instead of viewing surfaces, data are displayed in the whole volume.\n",
      "\n",
      "Begin to import the required module:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.volume import Volume"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "and then, add it to the source as usual:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "v = Volume()\n",
      "script.add_module(v)\n",
      "v.lut_manager.show_scalar_bar = True\n",
      "v.lut_manager.scalar_bar.orientation = 'vertical'\n",
      "v.lut_manager.scalar_bar.width = 0.1\n",
      "v.lut_manager.scalar_bar.height = 0.8\n",
      "v.lut_manager.scalar_bar.position = (0.01, 0.15)\n",
      "v.lut_manager.scalar_bar.label_text_property.color = fg_color\n",
      "v.lut_manager.scalar_bar.title_text_property.color = fg_color\n",
      "v.lut_manager.number_of_labels = 10\n",
      "v.lut_manager.data_name = \"\""
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Note that the Volume module has a \"Color Transfer Function\", which is\n",
      "quite different from the !LookUp Table used by the others modules.\n",
      "\n",
      "The rendered scene should look like this (thanks to Prabhu to have made\n",
      "the CTF similar to the LUT) :\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_volume.png)\n",
      "\n",
      "Vectors/Glyph/VectorCutPlane/WarpVectorCutPlane module\n",
      "------------------------------------------------------\n",
      "\n",
      "Until now, we have only dealt with scalar values. You can also display\n",
      "values as vectors. You can use one of the three following modules:\n",
      "\n",
      "`*\u00a0Vectors\u00a0module:\u00a0scale\u00a0and\u00a0color\u00a0are\u00a0set\u00a0by\u00a0vectors\u00a0data,\u00a0i.e.\u00a0a\u00a03D\u00a0array\u00a0vectors\u00a0field;`\n",
      "\n",
      "`*\u00a0Glyph\u00a0module:\u00a0scale\u00a0and\u00a0color\u00a0are\u00a0set\u00a0by\u00a0scalar\u00a0data;`\n",
      "\n",
      "`*\u00a0!VectorCutPlane\u00a0module;\u00a0in\u00a0this\u00a0case,\u00a0vectors\u00a0are\u00a0not\u00a0diplayed\u00a0in\u00a0the\u00a0whole\u00a0volume,\u00a0but\u00a0only\u00a0on\u00a0cutplanes,\u00a0as\u00a0!ScalarCutPlane\u00a0module\u00a0does\u00a0with\u00a0scalar\u00a0values.`\n",
      "\n",
      "You can set several parameters for these modules, in concern with arrows\n",
      "shape, etc.\n",
      "\n",
      "First, it depends of the number of points in your volume, but you are\n",
      "advised to decimate your data. If you don't, you should see nothing all\n",
      "but a lot of arrows everywhere, and thus loss the pertinent information.\n",
      "You can choose a randomly, or not, decimation.\n",
      "\n",
      "Second, you can choose the shape of your vectors, amongst the following\n",
      "list: 2D Glyph or Arrow, Cone, Cylinder, Sphere and Cube 3D vector\n",
      "shapes.\n",
      "\n",
      "Third, you can set some parameters for the choosen shape. For example,\n",
      "using the Arrow shape, you can set the following properties for the\n",
      "shaft and the tip:\n",
      "\n",
      "`*\u00a0the\u00a0shaft\u00a0radius;`\n",
      "\n",
      "`*\u00a0the\u00a0shaft\u00a0resolution\u00a0(number\u00a0of\u00a0polygons);`\n",
      "\n",
      "`*\u00a0the\u00a0tip\u00a0length;`\n",
      "\n",
      "`*\u00a0the\u00a0tip\u00a0radius;`\n",
      "\n",
      "`*\u00a0the\u00a0tip\u00a0resolution;`\n",
      "\n",
      "You can also set the vector position, between \"tail\", \"centered\" and\n",
      "\"head\", the scale mode, the color mode, the scale factor (how big your\n",
      "vectors will be displayed), etc.\n",
      "\n",
      "Let's see now how one can do this.\n",
      "\n",
      "First, import the required module.\n",
      "\n",
      "For Vectors module,"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.vectors import Vectors"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "For Glyph module,"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.glyph import Glyph"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "For !VectorCutPlane module,"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.vector_cut_plane import VectorCutPlane"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In fact, you will see that these three modules use the same objects and\n",
      "methods. Only default values differ.\n",
      "\n",
      "For instance, for Vectors module, you can type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "v = Vectors()\n",
      "script.add_module(v)\n",
      "v.glyph.mask_input_points = True             # we want to decimate our data...\n",
      "v.glyph.mask_points.on_ratio = 100           # ...by a ratio of 100\n",
      "v.glyph.mask_points.random_mode = True       # I want a randomly decimation\n",
      "v.glyph.glyph_source = v.glyph.glyph_list[1] # I like ArrowSource ;-)\n",
      "# following values are the default values: tweak your own !\n",
      "v.glyph.glyph_source.shaft_radius = 0.03     \n",
      "v.glyph.glyph_source.shaft_resolution = 6 \n",
      "v.glyph.glyph_source.tip_length = 0.35\n",
      "v.glyph.glyph_source.tip_radius = 0.1\n",
      "v.glyph.glyph_source.tip_resolution = 6\n",
      "v.glyph.glyph.scale_factor = 10\n",
      "v.glyph.glyph_position = 'tail'\n",
      "v.glyph.scale_mode = 'scale_by_vector'\n",
      "v.glyph.color_mode = 'color_by_vector'\n",
      "### if you use Glyph module, here are the default values\n",
      "# v.glyph.glyph_position = 'center'\n",
      "# v.glyph.scale_mode = 'scale_by_scalar'\n",
      "# v.glyph.color_mode = 'color_by_scalar'"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If we consider, once again ;-), the same 3D data already shown before,\n",
      "but this time, with vectors instead of scalars data, the scene should\n",
      "look like this:\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_vectors.png)\n",
      "\n",
      "For the !VectorCutPlane module, you can set the same properties as above\n",
      "plus the properties of the !ScalarCutPlane module such as\n",
      "implicit\\_plane.normal, implicit\\_plane.origin,\n",
      "implicit\\_plane.widget.enabled, etc:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "vcp = VectorCutPlane()\n",
      "script.add_module(vcp)\n",
      "vcp.glyph.mask_input_points = True\n",
      "vcp.glyph.mask_points.on_ratio = 5\n",
      "vcp.glyph.mask_points.random_mode = False\n",
      "vcp.glyph.glyph_source = vcp.glyph.glyph_list[1]\n",
      "vcp.glyph.glyph_source.shaft_radius = 0.03\n",
      "vcp.glyph.glyph_source.shaft_resolution = 6\n",
      "vcp.glyph.glyph_source.tip_length = 0.35\n",
      "vcp.glyph.glyph_source.tip_radius = 0.1\n",
      "vcp.glyph.glyph_source.tip_resolution = 6\n",
      "vcp.glyph.glyph.scale_factor = 20\n",
      "vcp.glyph.glyph_position = 'tail'\n",
      "vcp.glyph.scale_mode = 'scale_by_vector'\n",
      "vcp.glyph.color_mode = 'color_by_vector'\n",
      "vcp.implicit_plane.normal = (1, 0, 0) # set normal to Ox axis\n",
      "vcp.implicit_plane.origin = (10, 25, 25) # set origin to (i=10, j=25, k=25) for a structured grid\n",
      "vcp.implicit_plane.widget.enabled = True\n",
      "vcp.actor.property.diffuse = 0.0 # set some color properties\n",
      "vcp.actor.property.ambient = 1.0 # \n",
      "vcp.actor.property.opacity = 1.0 #\n",
      "vcp.module_manager.vector_lut_manager.data_range = [0, 1]"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This should render this scene:\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_vcp.png)\n",
      "\n",
      "You can also warp a cutplane according to the vectors field. To do this,\n",
      "you have to load another module, instead of !VectorCutPlane, called\n",
      "!WarpVectorCutPlane.\n",
      "\n",
      "Type:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.modules.warp_vector_cut_plane import WarpVectorCutPlane"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "then"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "wvcp = WarpVectorCutPlane()\n",
      "script.add_module(wvcp)\n",
      "wvcp.implicit_plane.normal = (1, 0, 0) # set normal to Ox axis\n",
      "wvcp.implicit_plane.origin = (10, 25, 25) # set origin to (i=10, j=25, k=25) for a structured grid\n",
      "wvcp.implicit_plane.widget.enabled = True\n",
      "wvcp.compute_normals = True\n",
      "wvcp.warp_vector.filter.scale_factor = 10"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You should get this (compare to the warped surface with !ScalarCutPlane\n",
      "module):\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_warpvcp.png\n",
      "\n",
      "Streamline module\n",
      "-----------------\n",
      "\n",
      "Another way to display vectors fields is to use the Streamline module.\n",
      "\n",
      "We consider here others Plot3D files: postxyz.bin & postq.bin that you\n",
      "can download [here](http://www.vtk.org/files/VTKTextbook/Data.tgz). You\n",
      "can find some screenshots using these files on the VTK home page\n",
      "[here](http://www.vtk.org).\n",
      "\n",
      "You can set several parameters for this module: for instance, the type\n",
      "of the streamline (tube, ribbon or line) with its properties, and the\n",
      "\"seed\".\n",
      "\n",
      "We also use the !GridPlane module in this example:\n",
      "\n",
      "Begin to import the required module:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "from enthought.mayavi.sources.plot3d_reader import PLOT3DReader\n",
      "from enthought.mayavi.modules.streamline import Streamline\n",
      "from enthought.mayavi.modules.grid_plane import GridPlane"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In this example, we want streamlines displayed as tubes, with 10 sides,\n",
      "and the seed set to the line seed. We also choose to display the\n",
      "\"Kinetic Energy\" part of the Plot3D files."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "src = PLOT3DReader()\n",
      "src.initialize('postxyz.bin', 'postq.bin')\n",
      "src.scalars_name = \"kinetic energy\"\n",
      "script.add_source(src)\n",
      "\n",
      "gp = GridPlane()\n",
      "script.add_module(gp)\n",
      "gp.grid_plane.axis = 'x'\n",
      "gp.actor.mapper.scalar_visibility = True\n",
      "gp.actor.property.representation = 'surface'\n",
      "gp.actor.property.diffuse = 0.0\n",
      "gp.actor.property.ambient = 1.0\n",
      "gp.actor.property.opacity = 1\n",
      "   \n",
      "gp = GridPlane()\n",
      "script.add_module(gp)\n",
      "gp.grid_plane.axis = 'z'\n",
      "gp.actor.mapper.scalar_visibility = False\n",
      "gp.actor.property.representation = 'wireframe'\n",
      "gp.actor.property.diffuse = 0.0\n",
      "gp.actor.property.ambient = 1.0\n",
      "gp.actor.property.opacity = 1\n",
      "\n",
      "strl = Streamline()\n",
      "script.add_module(strl)\n",
      "strl.streamline_type = \"tube\" # tube, ribbon or line\n",
      "strl.tube_filter.number_of_sides = 10\n",
      "strl.tube_filter.radius = 0.1\n",
      "strl.seed.widget = strl.seed.widget_list[1] # [Sphere, Line, Plane, Point]\n",
      "strl.seed.widget.align = \"z_axis\" # or \"x_axis\", \"y_axis\"\n",
      "strl.seed.widget.point1 = (-0.7, 0, 0)\n",
      "strl.seed.widget.point2 = (-0.7, 0, 4.82)\n",
      "strl.seed.widget.resolution = 10\n",
      "strl.seed.widget.enabled = False"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This should look like:\n",
      "\n",
      "![](files/attachments/MayaVi_ScriptingMayavi2_MainModules/module_streamline.png)\n",
      "\n",
      "Note: you can also see an example of using the Streamline module in [:Cookbook/MayaVi/Examples: Cookbook/MayaVi/Examples]."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}